Move the backlog to TODO.md and make that the fleet destination - #493
Merged
Conversation
The README carried a TODO section that spec/readme-structure.md never listed, so the hub's own README deviated from the structure the audit checks a fleet README against. Open work also does not belong on the adoption surface a reader lands on, and it changes on a different cadence from everything around it. TODO.md takes it, and readme-structure.md gains the section that makes it the fleet destination: a README carries no backlog section, and the backlog lives in a root TODO.md with a stated shape. The file is a declared destination rather than a required one, the same footing as ARCHITECTURE.md, so a repo with no backlog carries no file rather than an empty one. STANDUP.md step 2 lists it as the fourth topical destination. Three items are added while moving. The .editorconfig, .gitattributes and .gitignore comment cleanup and the repo-config/configure.sh sweep were both tracked only in an issue thread, and configure.sh is carried verbatim, so a downstream copy cannot fix its 54 findings locally and the hub owes the whole class. The third records the README's own 13 prose findings as deferred rather than dropped. The move also fixes what spec/readme-structure.md said about style. Its Style list instructed a README author to use a spaced hyphen, which GOVERNANCE.md bans in the same terms, so an agent following the more specific file produced prose the prose gate then flagged. That bullet now defers to the tiered character rule, and the eight other dash and semicolon findings in the file are fixed in the same pass. Raised from the Blog carry (#489, finding 1). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🟡 Not ready to approve
TODO.md does not fully follow the newly documented TODO-item format described in spec/readme-structure.md (items should include why the work is owed).
Once you've addressed the issues Copilot identified, you can request another Copilot review.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Pull request overview
Moves the repository’s running backlog out of README.md into a dedicated TODO.md, and updates the fleet documentation so TODO.md becomes the declared destination for backlog items rather than a README section.
Changes:
- Add
TODO.mdas the root running backlog and remove the## TODOsection fromREADME.md. - Extend
spec/readme-structure.mdto explicitly defineTODO.mdand state that READMEs should not contain backlog sections. - Update
STANDUP.mdto listTODO.mdas an additional declared destination for repo-specific content, linking to the README-structure spec.
File summaries
| File | Description |
|---|---|
| TODO.md | Introduces the committed running backlog file and link references. |
| STANDUP.md | Adds TODO.md as a declared destination for repo-specific backlog content and links to the README structure spec. |
| spec/readme-structure.md | Documents the new TODO.md convention and clarifies README section/order and style guidance. |
| README.md | Removes the TODO entry from the ToC and deletes the in-README TODO backlog section. |
Review details
- Files reviewed: 4/4 changed files
- Comments generated: 1
- Review effort level: Lite
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
The review asked why the first two entries state work without stating why it is owed, which the new spec section requires. Checking the two against the tree answered it differently: neither is live work. registry/repos.json carries no classificationPending marker at all, so that entry pointed at a state that no longer exists. And reports/ holds eight audit reports, so the first-audit entry was written before any of them landed and describes a starting condition rather than remaining work. One entry replaces both, scoped to the repos that still have no report and stating the reason a report is owed: a registry status of cataloged asserts a result that only a committed report evidences. The now-unused repos reference definition goes with it, since an orphaned definition fails the no-unused-defs rule. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🟢 Ready to approve
The changes are consistent across the docs/spec, and the README no longer contradicts the documented README structure standard.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Review details
- Files reviewed: 4/4 changed files
- Comments generated: 0 new
- Review effort level: Lite
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
ptr727
added a commit
that referenced
this pull request
Aug 1, 2026
…to main (#498) Promotes eight commits from `develop`. Every one traces to a defect found in use rather than to a planned change, and five came from downstream agents reporting what the procedure did not cover. ## What lands | Commit | Change | | --- | --- | | `a0f6f24` (#487) | `docs/content-import.md`, the three capture-pass findings from the Blog migration: an export is not a media capture, a sitemap is not the URL contract, and an HTTP fetch is not the original | | `8bdfa22` (#494) | The write-guard scopes by **owner** rather than exact origin, with `GH_WRITE_GUARD_ALLOW` for a different owner. Four target-flag spellings that silently bypassed rule 3 are closed | | `981d92f` (#492) | The purpose is restated as agent enablement, in `README.md`, `HISTORY.md` and `AGENTS.md` | | `275705b` (#493) | `TODO.md` becomes the fleet backlog destination, and `spec/readme-structure.md` stops mandating the construction `GOVERNANCE.md` bans | | `b6ab6db` (#491) | `STANDUP.md` step 0A names the maintainer-only prerequisites, and step 4 asserts the remote | | `89e3868` (#488) | The `version.json` floor is chosen at standup rather than inherited | | `eed2e00` (#495) | `README.md` gains "What It Achieves", the objectives and the fidelity ladder | | `f6dc5e6` (#497) | `CODESTYLE.md` stops claiming CI runs the same checks as the clean-compile | ## Provenance Five of the eight answer issues filed by downstream agents: #456 (Blog intake), #489 and #490 (the Blog carry), and #496 (Financial-Modeling). That loop is the one "What It Achieves" now describes, and this promotion is it closing. ## Divergence, checked rather than assumed `main...develop` reports `8 ahead, 102 behind, diverged`. **The 102 are topology, not content.** They are 79 promotion merge commits, which are main-only by construction because a promotion is a two-parent merge, plus 23 `Update codegen files` bot commits from this repo's pre-2.0 life as a .NET sample template. `git diff --name-status origin/develop origin/main` returns exactly the 12 files these 8 commits touch, so there is **no main-only content** to reconcile. ## Verification on the merged `develop` Every gate re-run after the last merge, not inherited from the individual PRs: - `prose_lint.py . --check charset --check dupword --check spelling` clean tree-wide. - `repo_gate.py` clean (`eol`, `sha-pin`). - `spec/validate.py` clean, 21 cataloged repos classify. - `gh-write-guard.py --selftest` passes, including the nine new repository-scope cases. - `python3 -m unittest discover -s scripts`, 180 tests pass. - The `README.md` objectives list verified as one continuous list of 8 bullets with the fidelity table nested, since an unindented table split it in review. ## Merge mechanics This is a promotion, so it merges as a **merge commit** with two parents, never a squash. Its head **is** `develop`, so `--delete-branch` must not be used. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Moves the running backlog out of
README.mdintoTODO.md, and makes that placement the fleet standard rather than a hub preference.Why the README was the wrong home
spec/readme-structure.mdlists twelve README sections and TODO is not one of them, so the hub's own README deviated from the structure its audit checks every fleet README against. Beyond conformance, open work does not belong on the adoption surface a reader lands on, and it changes on a different cadence from everything around it.What makes it a standard
spec/readme-structure.mdgains aTODO.mdsection, stating that a README carries no backlog section and that the backlog lives in a rootTODO.mdwith a defined shape. This is the file thereadme-structureaudit dimension reads, so the rule lands where the check already looks.STANDUP.mdstep 2 lists it as the fourth topical destination, alongsideCODESTYLE.md,ARCHITECTURE.md, andOPERATIONS.md.It is a declared destination, not a required file, the same footing as
ARCHITECTURE.md, so a repo with no backlog carries no file rather than an empty one. Say the word if you would rather it be required by a selector, which would mean aspec/files.jsonentry and an emptyTODO.mdin every repo.Fleet impact is small, and measured
Surveyed live across twelve repos: no repo has a
TODO.md, and exactly three carry a README## TODOsection, all of them operational config repos (HomeAssistant-Config, Vantage-Config, HomeAutomation-Config). The other nine have neither, so they are already conformant. Those three are a follow-up, not this PR.Two things fixed while in these files
spec/readme-structure.mdinstructed authors to use the constructionGOVERNANCE.mdbans. Its Style list said "ASCII only (no em-dash; use a spaced hyphen)", againstGOVERNANCE.md"No spaced hyphen joining or interrupting a sentence", so an agent following the more specific file produced prose the prose gate then flagged. The bullet now defers to the tiered character rule, and the file's other 8dashandsemicolonfindings are fixed in the same pass. This closes finding 1 of Carry findings from Blog: spec conflicts, prose_lint false positives, and two silent carry hazards #489..editorconfig/.gitattributes/.gitignorecomment cleanup (44 findings), therepo-config/configure.shsweep (54 findings, and that file is carriedverbatimso downstream cannot fix them locally, which is finding 6 of Carry findings from Blog: spec conflicts, prose_lint false positives, and two silent carry hazards #489), and the README's own 13 prose findings.The README sweep is deferred, deliberately
README.mdcarries 13dashandsemicolonfindings, none on lines this PR touches. Two other changes to that file are in flight (#492), so a third overlapping edit would conflict with both for no gain. It is recorded inTODO.mdrather than left to memory, which is what that file now exists for.Verification
prose_lintblocking set clean tree-wide.TODO.md,STANDUP.md, andspec/readme-structure.mdclean on the warn set too.[reports]and[repos]are still used elsewhere in the README.🤖 Generated with Claude Code